17 Bit Software 6: Level 6

home *** CD-ROM | disk | FTP | other *** search

/ 17 Bit Software 6: Level 6 / 17 Bit - Level 6 (1998)(Epic Marketing)[!].iso / !commodities! / docs / kcommodity.man < prev next >

Wrap

Text File | 1996-09-07 | 121KB | 4,210 lines

KCommodity V2.00 for the Amiga running OS 2.0 by Kai Iske 7th September 1992 Contents 1 Introduction 4 1.1 Copyright ....................................................... 4 1.2 Guarantee ....................................................... 4 1.3 Evolution ....................................................... 4 1.4 Installation .................................................... 5 1.5 For users of older versions ..................................... 5 2 Starting the program 6 2.1 Starting from Workbench ......................................... 6 2.2 Starting from CLI / SHELL ....................................... 6 2.3 The program`s ToolTypes ......................................... 7 3 Overview of functions 10 3.1 Fundamental topics for the usage ............................... 10 3.1.1 The AppIcon and the AppMenuItem ......................... 10 3.1.2 The HotKeys ............................................. 11 3.1.3 The windows ............................................. 11 3.1.4 The gadgets .............................................. 11 3.2 Special features of KCommodity ................................ 13 3.2.1 The window activator .................................... 13 3.2.2 Autocenter .............................................. 13 3.2.3 MMB-Shift ............................................... 13 3.2.4 NoClick ................................................. 14 3.2.5 WildStar ............................................... 14 3.2.6 The time display ........................................ 14 3.2.7 The online time .......................................... 14 3.2.8 The memory display ...................................... 15 3.2.9 Alarm function .......................................... 15 1 CONTENTS 2 3.2.10 Keystroke clicker ....................................... 15 3.2.11 Environment variables ................................... 15 3.2.12 Screen / Window cycling ................................ 15 3.2.13 Windowreactivation ...................................... 16 3.2.14 LeftyMouse .............................................. 16 3.2.15 Closing windows using the ESC key ....................... 16 3.2.16 Mapping of "Umlauts" ..................................... 16 3.2.17 Screen / Mouse Blanker .................................. 17 3.2.18 Mouse accelerator ...................................... 17 3.2.19 Mouse locking .......................................... 17 3.2.20 Mouse coordinates ....................................... 17 3.2.21 Exploding Windows ....................................... 18 3.2.22 Full drag .............................................. 18 3.2.23 Funktion keys ............................................ 18 3.2.24 Formatter ............................................... 18 3.2.25 Memory "Snapshot" ....................................... 18 3.2.26 Opening a shell via HotKey .............................. 19 3.2.27 Telephone bill calculator ............................... 19 3.2.28 Revision Control System .................................. 19 3.2.29 Display dump ............................................. 19 3.2.30 ARexx Port .............................................. 19 4 The telephone bill calculator 20 5 The revision Control System 22 5.1 First revision of a sourcecode with the Revision Control System 23 5.2 Revision of an already revised sourcecode ...................... 24 5.3 The revision header`s special features .......................... 26 6 Usage within the windows 28 6.1 The main window ................................................. 28 6.1.1 Functions, which can not be reached via gadgets .......... 31 6.2 The Settings window ............................................ 31 6.3 The Miscellaneou window ........................................ 34 6.4 The Alarm modes window ......................................... 36 6.5 The Blanking window ............................................ 37 6.6 The Cycling window ............................................. 38 6.7 Display colors ................................................. 39 6.8 The Mouse window ................................................40 CONTENTS 3 6.9 The HotKeys window ............................................ 41 6.9.1 Description for defining a HotKey ....................... 45 6.10 The Display dump window ....................................... 46 6.11 The Funktion Keys window ....................................... 50 6.12 The Formatter window ............................................ 52 6.13 The Lock windows window ....................................... 54 6.14 The Bill window ............................................... 55 6.15 The Preferences window ......................................... 56 7 The ARexx Port 59 7.1 Commands for the ARexx Port .................................... 59 7.2 Status numbers ................................................. 63 A Error codes 67 B Why KCommodity ? 71 Chapter 1 Introduction 1.1 Copyright You are allowed to copy and spread this program but only if you do not make any commercial profit out of the program itself and all supported files. The source of KCommodity is considered teachware and the author claims the right to be the only one to produce and distribute new versions of KCommodity. Public Domain vendors are not allowed to sell KCommodity for more than the price of a regular disk. 1.2 Guarantee The author does not give any guarantee that the program KCommodity works perfectly. The program was tested and it is used every day, anyway nobody is perfect and that is why I can not take the responsibilty for any damages occured during the usage of KCommodity. 1.3 Evolution KCommodity was developed out of the need to reduce the amount of smaller programs, which should ease the daily work with the computer. Instead I wanted to create an effecient program, which should implement the functions of these utilities and that my program might go one step further. At first KCommodity only consisted of a window activator, which gave me the pos- sibility to activate windows via keystroke or via mouse movement. Growing knowledge of the new Operating System and the eagerness to minimize the 4 CHAPTER 1. INTRODUCTION 5 number of running utilities there were more functions to be implemented into KCommodity. So KCommodity became bigger and bigger but it`s size, in comparison to it`s functions, was held small. Now I`ve come to a point that KCommodity almost completely suits my needs and that it replaces other programs of it`s kind. I hope that you like the supported functions as much as I do and I wait for any suggestions to implement new, powerful functions. 1.4 Installation You may copy the main program KCommodity to any location on your (Hard)Disk. If you want to have it started on every boot-up I recommend to place it within the SYS:WBSTARTUP drawer of your Workbench. You can copy the KCX.PREFS file to the ENVARC:KCX/ drawer. Maybe you will have to create the KCX/ directory yourself: MakeDir ENVARC:KCX. If you do not copy the KCX.PREFS file to this drawer KCommodity will use it`s built-in defaults, if the preferences file can not be found in any of the programs`s search paths. The KCX.PREFS file will be loaded on every startup, so you will have to save your main preferences to that file. 1.5 For users of older versions Because of the many changes made to KCommodity since the last release I could not keep up the old preferences format. Just because of these changes it would not have been reasonable to program a converter for older prefe- rences files. You will have to do adjust your settings by hand and delete the old files. Chapter 2 Starting the program KCommodity can be started either from Workbench or from CLI / SHELL. 2.1 Starting from Workbench If you start KCommodity from Workbench, you may enter some preferences into the .info file of the program, which will be loaded on startup. Within the .info file there should be another ToolType set except for these discussed in The program`s ToolTypes. This ToolType will prevent the Workbench from waiting until KCommodity stops, if the program was launched during boot time (assuming that the program is located within the SYS:WBStartUp drawer). This ToolType is called DONOTWAIT. 2.2 Starting from CLI / SHELL Of course you can start KCommodity from your CLI / SHELL, but you have to know that KCommodity does not detach itself from the CLI / SHELL so you will have to use RUN / RUNBACK1 to prevent KCommodity from blocking the environment of your CLI / SHELL. When you start KCommodity you can supply the same ToolTypes within the commandline as described in The program`s ToolTypes. Instead of using one form for supplying parameters within the .info file you have two on the commandline. The first is to have a `=' between the keyword and the value and the second is to have 1 The latest version of RunBack can be found on Fred Fish Disk 429 6 CHAPTER 2. STARTING THE PROGRAM 7 a space between them. Remember that parameters which include spaces should be enclosed in brackets. e.g. "CX POPKEY=LALT HELP" or CX POPKEY "LALT HELP" Additionally you have the possibility to retrieve a little Helptext. The syntax is as follows: KCommodity Help This command will print out a little table showing all available ToolTypes. Starting KCommodity like this KCommodity ? will show you a list of all available ToolTypes giving you the possibility to type in the requested keywords and start the program. 2.3 The program`s ToolTypes KCommodity knows some ToolTypes which can either be located within the .info file or may be issued on the command line. The syntax should be of the form ToolType=Value. If you start the program from a command line you can leave out the `=' and replace it by a space. Here are the ToolTypes the program recognizes. CX PRIORITY=n Sets the priority for the program`s section which controls the HotKeys. If you issue a priority > 0 it may be that HotKeys initial- ized by other programs may not be reached anymore if KCommodity uses the same. De- fault: It`s neutral 0. CX POPKEY=s Lets you define a new HotKey for opening KCommodity`s main window. The Value for this ToolType will overwrite the definition loaded from the Preferences file. Default: LCOMMAND HELP. CX POPUP=YES|NO You can choose whether the main window should be opened on startup or not. Issuing CHAPTER 2. STARTING THE PROGRAM 8 YES will open the window whilst NO will keep it away. Default: YES. PORTNAME=s You can select a different name for the pro- gram`s ARexx-Port. Please remember that this name`s length should not exceed 16 chars. Normally this will be KComm.1. TOOLPRI=n This one is used to set the priority for the pro- gram itself. This may be usefull while running other programs of KCommodity`s kind, since they might conflict. Just set the priority to a slightly higher value and all the problems should be gone. Default: Again the neutral 0. HANDLERPRI=n This ToolTypes lets you define the priority for the InputHandler. This Handler is used to control KCommodity`s functions like window activator etc.pp. If you use other programs like KCommodity it may happen that these conflict. Just supply a higher priority and it should be done. Remember that the minimum priority for such a Handler is 51. Default: 55. SETTINGS=s You can have a different Preferences file to be loaded on startup. If KCommodity is not suc- cessful in finding the specified file it will try to open the default KCX.PREFS within the current directory. If this attempt also fails it will look for the file within ENV:KCX/. If that one could not be found, too, KCommod- ity will use it`s built-in defaults. NOICON This simple ToolTypes tells KCommodity not to generate the AppIcon2 on the Workbench. NOMENU If do not want to have the AppMenuItem2, too, use this ToolType. ICONX Using this ToolType you may specify the Ap- pIcons X-Position. Default setting is that the Workbench should find a suitable location. 2 See The AppIcon and the AppMenuItem CHAPTER 2. STARTING THE PROGRAM 9 ICONY Same as above, with only one exeception. This ToolType controls the AppIcon`s Y- Position on the Workbench Screen. Chapter 3 Overview of functions KCommodity offers a variety of functions and in fact some of them might not be helpfull for you but the program was designed to cover almost every possiblity in helping the user. If you find certain functions to be useless you can deactivate them of course. 3.1 Fundamental topics for the usage KCommodity offers some windows from which you can retrieve information or change the program`s settings. This section will explain the different functions. 3.1.1 The AppIcon and the AppMenuItem If not chosen differently when started, KCommodity will display an AppIcon on the Workbench screen. This icon does not have anything to do with normal Worbench icons. These stand for programs which can be started by a double-click on the corresponding icon which is defined within the program`s .info file. An AppIcon is a so called Applications Icon. This type of icon is generated by programs from which the user may communicate with the program. For KCommodity the AppIcon only has one function: A double-click on the icon will open up the main window. Furthermore KCommodity will generate an AppMenuItem which is appended to the Tools menu of the Workbench. Each program can add one (or more) entries to that menu. The method of selection of one of these entries is the same as for "normal" menus. KCommodity will add a menu entry 10 CHAPTER 3. OVERVIEW OF FUNCTIONS 11 called KCX Main-Window from which you can open the program`s main window. 3.1.2 The HotKeys KCommodity supports several HotKeys. Take a look at chapter The HotKeys window for further information. 3.1.3 The windows The gadgets within the windows do have an underlined char within their descriptive text. Using this key you can control gadgets via keyboard. All windows may be closed by a single hit on the ESC key or by hitting the Close Gadget. 3.1.4 The gadgets As mentioned above a gadget`s descriptive text contains an underlined char. This char is a shortcut for reaching a gadget without clicking on it. Cycle, Slider, and ListView Gadgets offer one more possibility in controlling them via keyboard. If you hit the shortcut unshifted theses Gadgets will scroll forward in their selection. A shifted shortcut will scroll backward. Within KCommodity`s windows String Gadgets do have some special features for editing, which in fact are not available within the normal system. Here is a list of features which are supported by the Operating System: RIGHT AMIGA X Clears the current input. RIGHT AMIGA Q Restores the previously cleared input, which might has been deleted using RIGHT AMIGA X. TAB Activates the next available gadget. Gad- gets are cycled through. SHIFT TAB Activates the previous gadget. HELP Will exit the String Gadget. CURSOR LEFT The cursor is moved to the left. CURSOR RIGHT The cursor is moved to the right. DEL Deletes the char underneith the cursor and moves text, which may reside to the right of the cursor, to the left. CHAPTER 3. OVERVIEW OF FUNCTIONS 12 BACKSPACE Deletes the char left to the cursor and moves the cursor one position to the left, while any text to the right of the cursor is also moved to the left. Has no effect if the cursor already is at the leftmost position. RETURN End an input. And now to the functions supplied to KCommodity`s String Gadgets. Some of the "normal" features get enhanced functions: RETURN The currently active String Gadget is ex- ited from and the next available gadget will be activated. Gadgets are cycled through. SHIFT RETURN Like RETURN but the previous gadget will be activated instead. CURSOR DOWN Like RETURN. CURSOR UP Like SHIFT RETURN. CTRL CURSOR LEFT Moves the cursor to the next word to the left of the cursor`s current position. Has no effect if the cursor already resides at the first position of the box. CTRL CURSOR RIGHT Moves the cursor to the next word to the right of the cursor`s current position. This function has no effect if the cursor already is positioned at the end of the in- put line. RIGHT AMIGA + key This function offers the possibility to reach menu entries from within String Gadgets. Therefore it is of no need to exit a gadget for activating a menu entry or another gadget. The currently active gadget will be reactivated (if there is a need for). CHAPTER 3. OVERVIEW OF FUNCTIONS 13 3.2 Special features of KCommodity Now I would like to come to the special functions KCommodity offers which make the program worth using. Mainly these functions exist for helping you while working on your Amiga. 3.2.1 The window activator This feature serves for activating windows by a simple keystroke while the mouse pointer resides over a window. So move the mouse to the desired window and just start typing. KCommodity will immediately activate the window and it redirects the input to this window. The second possibility for activating windows is to use the mouse. In this mode every window will be activated which is touched by the mouse. If you move the mouse at a higher speed windows will not be activated. Windows will only be activated immediately if the mouse is moved at a lower speed or over a short distance. This window activator is so intelligent not to deactivate windows active String Gadgets are in, if the mouse is not located over the window containing the gadget. So you can make your input without having to worry about the mouseposition. KCommodity offers the possibility to define windows which are not to be deactivated when using the window activator. This is accomplished by simply specifying the window`s name. You can use Wildcards for specifying the names. System-Requesters, as created by AutoRequest() and EasyRequest(), will automatically deactivate KCommodity`s window activator, so you may control these Requesters via keyboard. 3.2.2 Autocenter KCommodity is able to center screens horizontally which do not have the full width, so that these screens are not "glued" to the upper left edge of the display. Already open screens may be recentered using a HotKey. 3.2.3 MMB-Shift Is abbreviation for "Middle-Mouse-Button Shift". This feature aids you in multiselecting Icons on the Workbench. While you are multiselecting there is no need to press the Shift key anymore, simply hit your middle mousebutton. CHAPTER 3. OVERVIEW OF FUNCTIONS 14 3.2.4 NoClick This option turns off drive clicking. 3.2.5 WildStar When starting KCommodity, the program will set a special flag within a DOS structure, so you can use the '*' as Wildcard within the Shell. 3.2.6 The time display KCommodity offers many possibilities for displaying the actual system time. No matter which display mode you choose the actual hour and minutes will be displayed. But there are several different modes you can choose from: 1.Display the current day (a) In full length (b) Only three chars (e.g. Mon, Tue, ... ,Sun) 2.Display the actual date (a) In German notation (DD-MM-YY) (b) in American notation (MM-DD-YY) The daynames may either be shown in German or English notation. Be- tween the digits of the datestring there may either be '-' or '.'. As you can see there are many possibilities to vary the display of the actual system date. Just have a look at chapter The HotKeys window to get to know other topics concerning this display. 3.2.7 The online time I implemented this feature with users of modems in mind (including me). Besides the time display there is one more display. KCommodity is able to display the time you are connected to a Bulletin Board System. KCommodity will start the timer when a Carrier is detected. CHAPTER 3. OVERVIEW OF FUNCTIONS 15 3.2.8 The memory display There is another display mode. KCommodity offers a small variety of modes for displaying the free system memory. There are three modes available: 1.Displaying the free Chip / Fast memory seperately. 2.Displaying the total free memory as digits. 3.Displaying the total free memory as a gauge. Have a look at chapter The HotKeys window to learn how you can reach these display modes. 3.2.9 Alarm function KCommodity offers the possibility to "wake" you up. By entering an alarm time and activating the alarm KCommodity will remind you at the given time. Furthermore KCommodity can wake you up on every full hour. If you find that flahsing display or the soft beep to be inaccurate to wake you up, you may select an IFF Format sound, which will be played at every alarm. 3.2.10 Keystroke clicker You probably know this feature from professional keyboards. These key- boards produce a clicking sound when a key is hit. This feature is simulated by KCommodity. You can set the volume for producing the sound to have an acceptable simulation. 3.2.11 Environment variables If you want to offer the current system time to another application, which does not supply a time display, but is able to read environment variables then you can tell KCommodity to generate environment variables for you, which contain the actual system time and date. 3.2.12 Screen / Window cycling Probably you know that problem: There are several windows open and you would like to move one to front, but it`s Depth Gadget is hidden by others and you only see a small part of the desired window. Normaly you would CHAPTER 3. OVERVIEW OF FUNCTIONS 16 have to click the other windows to back to uncover the Depth Gadget so you can click the window to front. Not while KCommodity is running. Just move the mouse over a part of the window and press one of the selected keys to bring it to front. Surely it is possible to bring a window to back the same way. If you try to move a BackDrop window (e.g. the WorkBench window) the whole screen will be brought to front / back. This also happens, if the mouse is located right over a screen. Users with a three-button-mouse can use the Screen Cycling by hitting the middle mousebutton. These keystrokes may be altered by the user. Furthermore you can select the number of "clicks" to occure before the selected function will be executed. 3.2.13 Windowreactivation While flipping through screens KCommodity will remember the currently active window on every screen you leave. When turning back to that screen, KCommodity will reactivate the window. 3.2.14 LeftyMouse This is a small function for lefties. KCommodity can swap the left and right mousebuttons for you, so that lefties may use the "left" mousebutton for clicking into windows. 3.2.15 Closing windows using the ESC key Isn`t it quite unsatisfactory to hit a Close Gadget every time you want to close a window? Let KCommodity close windows which have a Close Gadget. Many programs on PCs offer the possibility to quit programs or to close "windows" by hitting the ESC key. This option is emulated by KCommodity. Due to the fact that not every program has no function tied to the ESC key it is possible to set a qualifier, so that no incompatibilities may arise. 3.2.16 Mapping of "Umlauts" Owners of a modem will like this feature. Because German "Umlauts" are mapped differently on different computer systems KCommodity offers the possibility to convert these character to "normal" chars. The pendants (ae, oe, ue, ss) will be generated case-sensitively. CHAPTER 3. OVERVIEW OF FUNCTIONS 17 3.2.17 Screen / Mouse Blanker KCommodity may blank the screen or the mouse for you so that the screen may not burn into the monitor`s display while there is no input from the usse. The mousepointer will be blanked automatically so that the mouse does not cover part of your input and that you can see what you are writing. You can choose from two modes for the Screen Blanker. First there is the normal blanker which completely blanks the screen. Secondly there is the Dimmer which gives you the possibility to set a factor for dimming so that there still will be some parts visible but the colors will not be that bright anymore. This does not prevent the picture from burning into the monitor ! People who hope to have another "well-behaved" blanker with KCommodity are to be disappointed now. KCommodity`s blanker does something you expect a blanker to do. It blanks the screen and does not flip around. Users who prefer a flipping blanker should use Spliner instead. This program by Tim Rokicki and Sebastiano Vigna is a very "well-behaved" program, the two did a great job on. That`s why it did not seem worth to try to "beat" this program. 3.2.18 Mouse accelerator KCommodity can accelerate the mouse for you, that means the mousepointer will be moved faster although you are moving the mouse at a low speed / range. You can alter the acceleration factor and the threshold. The threshold is used for movements at a low range / speed. If the mouse is moved within that range it will not be accelerated. Otherwise KCommodity will accelerate the pointer with the given factor. 3.2.19 Mouse locking In some situations it is preferable that the mouse movement should be locked in certain directions (like positioning an Icon on the Workbench). That`s why KCommodity offers the possibility to lock the mouse movement. You can lock horizontal and vertical movements. 3.2.20 Mouse coordinates The actual mouse coodinates (relative to the actual Screen) may be printed out, so that you always know where you are. CHAPTER 3. OVERVIEW OF FUNCTIONS 18 3.2.21 Exploding Windows This is more a hack than a "useful" feature. With an active Exploding Windows function on opening a window frames will be drawn from the center of the screen to the window`s new position. It seems like the window is smoothly growing to it`s full size. When closing the window the motion will go the other way around. First the window will be closed and then the frames will be drawn back to the center of the screen. This function does not have any effect on backdrop windows. But it does not have to be the screen`s center. Alternatively you can tell KCommodity to use the actual mouse position as the animation`s focus. Additionally there is another feature. If you move a window, size it or "zoom" it frames will be drawn from the window`s current position to the new one, that means the metamorphosis will be shown. To shorten the time for exploding / imploding the frames on "slow" Amigas you have the possibility to set the number of frames to be drawn for exploding, imploding and sizing / moving / zooming. 3.2.22 Full drag Using KCommodity there is no need to click on a window`s titlebar in order to move that window. Just click inside the window and perform the movement as if you clicked on the titlebar. 3.2.23 Funktion keys The ten function keys may be equipped with four strings. It is possible to map three special strings on a function key which will perform special operations. 3.2.24 Formatter KCommodity may check every inserted disk, whether it is already formatted or not. If not, KCommodity will give you the opportunity to format that disk just inserted. This function may also be called seperately. 3.2.25 Memory "Snapshot" Using this function you are able to make a snapshot of the currently available memory. A second call of this function will show the difference between the first and the second call so you can see how much memory was used / freed CHAPTER 3. OVERVIEW OF FUNCTIONS 19 by programs launched / stopped between the two calls. You can now analyze if a program really freed all needed memory. 3.2.26 Opening a shell via HotKey You may open a shell by pressing a HotKey. With KCommodity you can define the command to be executed exactly the same way as to be issued on the commandline. 3.2.27 Telephone bill calculator Again a small help for owners of modems. As soon as you log into a BBS, KCommodity will recognize the Carrier Detect and start counting the time and costs while you are connected to the BBS. 3.2.28 Revision Control System This feature was made for programmers. While you are working on a larger program you will sometimes reach a point you would like to record some in- formation about the development of the program. KCommodity aids you in doing this. You can insert the Revision Header directly into your sourcecode. These headers may be generated for Assembler, `C', Basic and Pascal / Modula sourcecodes. 3.2.29 Display dump KCommodity may dump the actual Screen/Window on a printer. You have full control over the look of the dump and area to be printed. 3.2.30 ARexx Port KCommodity is equipped with an ARexx Port, from which you may retrieve any of the program`s settings or change any of the defaults. Some functions may only be activated via the ARexx Port (Revision Control System). Chapter 4 The telephone bill calculator Some of you own a modem but as you probably know (including me) you can never definitly say how much the calls cost you made. That is why I included this feature. The telephone bill calculator can be fully configured to your needs. You can choose between three different time zones either normal or cheap tariff for all of which you may set the duration for one unit. KCommodity can not deal with one hundreds of a second but anyway, inaccurances may occure while counting the time because of intolerances (somewhat of about 1100 seconds is not that bad I guess and fixing that problem would have caused some more trouble). Maybe there will be a better possibility to enter the time. You can enter the "cost" for one unit (without that it really would not make much sense). The input is made in somewhat like cents, Pfennige, say in micros, but I think that is sufficient, since there might not be an currency which counts in millis. Furthermore you can define the times for normal and cheap tariffs. KCommodity will check the actual system time to see which of the two tariffs should be used. Weekdays on which cheap tariff should be used the whole day may be marked, too. As soon as the program detects a Carrier, that means if the modem establishes a connection to a BBS, KCommodity will start to count the time. You can tell the program to open up the Bill window on a Carrier Detect. Data about the phone call may be written to a log file, so that it can be analysed later and you can get an overview of arisen costs. KCommodity also aids you in listing the data. The program will print out all entries of the log file giving a total summary after the listing of one day and a final sum after all entries have been listed. This printout may be redirected to a 20 CHAPTER 4. THE TELEPHONE BILL CALCULATOR 21 file or you can view it in a window. As mentioned above I do not take any responsibility for the correct work- ing of the telephone bill calculation, because slight inaccuracies may occure within the system`s timer. Additionaly it is of importance that you enter almost perfect times, because KCommodity`s results are only as good as your inputs are. This function has only been implemented to have a rough overview of costs. Chapter 5 The revision Control System This really is a fine feature. It might be interesting for the programmers of you, which are working on bigger, or even on smaller, projects. While working on a program it might be nice to see which changes were made to a program from this to that version. Inserting this data by hand is not quite that what I call simple. This is where KCommodity`s Revision Control System gets to work. This feature aids you in inserting good looking Revision headers directly into your sourcecode. All you have to do is to tell KCommodity the program`s name to be revised, what kind of sourcecode it is and what information KCommodity should insert into the Revision header. For the type of sourcecode you can choose between Assembler, Basic, `C', and Pascal / Modula. The main layout of the header is kept but only adjusted to perfectly fit into the desired type of sourcecode. The special thing about the function is the way it is called. The Revision Control System can only be called via ARexx. That is why I present the syntax for that call now: REVISE Filename ASM|BAS|C|PAS As you can see all you have to do is to feed the function with the filename and an identifier for the type of sourcecode. Having started the Revision Control System KCommodity will first search the sourcecode whether there already is a Revision header inserted in the specified language. There is no need to position the header at the first line of the source. KCommodity will search within the first 15 lines to find the header, giving you the possibility to add specific directives in front of the header. So it is possible to insert text in front of the header1. No matter if there already is a header this search will 1 Some Assemblers require special information within the first line of the source. 22 CHAPTER 5. THE REVISION CONTROL SYSTEM 23 always be made when the Revision Control System is called. From now on KCommodity will go different paths in manipulating the source, depending on the existence of a header. Make sure that the logical directory T: is accessible, because KCommod- ity needs that directory to temporarily store it`s work. To be secure I advise you to make a backup of your sourcecode before you start the Revision Control System. (One can never know) If you want the program to store your name and the name of your `firm' within the header you will have to set two environment variables. AUTHOR Set this variable to your name. COMPANY Enter your firm`s name here. Now following is a small example for setting these variables: SETENV AUTHOR "Kai Iske" SETENV COMPANY Gunthersoft As you can see parameters which contain white spaces have to be enclosed by quotes. Insert these settings within your s:User-StartUp file to have the variables available on every bootup. 5.1 First revision of a sourcecode with the Revision Control System Assuming this situation I will now point out the actions KCommodity per- forms when first used on a non-revised sourcecode. A window will be opened with the following title: You can now enter a 5 lines (60 chars per line) Purpose Message As the title says you are now to enter a purpose for the sourcecode you want to revise. You have the possibility to enter 5 lines and 60 chars per line. When you are done with the purpose message you can enter some more specific data. You can tell KCommodity which version number to use for the first revision. This input is made within the Integer Gadgets at the bottom of the window. The left gadget is used to enter the version number. Into the right gadget you can enter the revision number. Entering `0'.`0' KCommodity assumes that you do not mind if the program automaticaly uses `1.0' for the version CHAPTER 5. THE REVISION CONTROL SYSTEM 24 number. The gadgets OK and CANCEL are self-explanatory. Whilst OK starts the revision CANCEL is used to abort. Assuming that you have made all the input and started the Revision Control System I will now describe the actions KCommodity will take for building the header. At first a part of the standard header will be built. The production will be made within T:. If the environment variables are set the author`s and the `firm`s' name will be stored within the header. If KCommodity was not able to find one variable, or even both of them, the corresponding fields will be set to ` Unknown '. Furthermore the filename and the actual system date will be inserted. The current revision will be set to the value you specified or to the value KCommodity automaticaly uses. Now the `purpose' text will be inserted and finally a `log message' for the current revision will be appended to the header. This log message will be set to ` Initial release ' for the first revision, because it is assumable that no changes have been made. Behind the log message KCommodity will insert six macros, which reflect date of the revision, time of the revision, name of the author, who made the revision, the current revision number of the sourcecode and version/revision numbers. Please have a look at chapter The revision header`s special features for further information. The Revision header will be created at the start of the sourcecode, so you will have to insert lines which have to be in front of the header, after you revised the source. 5.2 Revision of an already revised sourcecode If there already was a header within the sourcecode KCommodity will now go the second way. Again a window will be opened which does not visually differ to the Log window. The window`s title is: You can now enter a 5 lines (60 chars per line) Log Message You can enter a descriptive text for all changes made to the source since the last release (Log message) here. The two Integer Gadgets at the bottom of the window can be used to set the new revision number KCommodity should continue with. If you leave the gadgets set to `0'.`0' KCommodity in- creases the actual revision number by .01. Otherwise it will use the supplied number. Selecting OK you tell KCommodity to continue whilst CANCEL aborts the procedure. Did you tell KCommodity to continue only important entries will be changed within the header. The actual revision number will be set to the new CHAPTER 5. THE REVISION CONTROL SYSTEM 25 value and the log message will be inserted before the previously entered. The log message`s header gives you information about the author of the revision and when the changes were made. Finally the macros behind the header will be recreated. For further information have a look at section The revision header`s special features. The header`s postion within the source will be kept unchanged but the source`s length will increase slightly. If the first of the six macros could not be found right after the header, KCommodity assumes that you no longer want the program to rebuild the macros and so it does not make a refresh. So if you insert a blank line between header and macros no more changes will be made to them. CHAPTER 5. THE REVISION CONTROL SYSTEM 26 5.3 The revision header`s special features Here is a small example for the look of the header in Assembler. ; ; A maximum of 14 lines above the header ; ;* $Revision Header built automatically *************** (do not edit) ***** ;* ;* Copyright by <COMPANY> ;* ;* File : <this would be the name of the file> ;* Created on : Sunday, 05-01-92 02:27:25 ;* Created by : <AUTHOR> ;* Current revision : V1.01 ;* ;* ;* Purpose ;* ;* This is just a test for the purpose string ;* and a second line ;* ;* Revision V1.01 ;* ;* changed on Sunday, 05-01-92 02:27:45 by <AUTHOR>. LogMessage : ;* And a test for a LogMessage ;* second line ;* third line ;* ;* Revision V1.00 ;* ;* Initial release ;* ;************************************************************************** REVISION MACRO dc.b "1.01" ENDM REVDATE MACRO dc.b "05-Jan-92" ENDM REVTIME MACRO dc.b "02:27:45" ENDM AUTHOR MACRO dc.b "Kai Iske" ENDM VERNUM EQU 1 REVNUM EQU 01 ; ; This is where your sourcecode would start at ; CHAPTER 5. THE REVISION CONTROL SYSTEM 27 This is the header of an Assembler sourcecode which was revised once after it was created. The field <COMPANY> will be filled with the name of the company (if present). The <AUTHOR> fields will be filled with the name of the author as long as the environment variable could be found. At the end of the header you find six macros. These macros reflect the actual revision number, date of revision, time of revision,the name of the author having done the revision and version/revision number. You can use these macros within your sourcecode, so that you can tell the user something about the program`s "evolution" during runtime. The Basic, `C' and Pascal / Modula pendants take the same names as in Assembler. The `C' type macros will be set as #defines into the sourcecode. As you might believe the Basic versions are string variables which have a $ prepended. There is one thing to remember while using the Pascal / Modula macros: To make these macros available within sourcecodes I chose the possibility to declare the macros as CONSTants. Therefore the CONST symbol will immediatly follow the header and then following are the macros. So you will have to add any other constant declarations after KCommodity`s. Chapter 6 Usage within the windows On startup KCommodity`s main window will open up (if not selected differ- ently). This chapter tells you how you can control the window`s functions and to manipulate the behaviour of the programs`s features. Furthermore some "small" functions will be described here. Except for the Telephone bill calculator and the Revision Control System you will find all the information you need to configure KCommodity and you will get to know the other possibilities the program offers. I do not mention each function seperately because it would have been a useless waste of time and space. The description will be made window by window whilst special options will be pointed out seperately. 6.1 The main window This window is considered to be a control panel to reach other windows from. You may reach the following windows: ° Settings ° Miscellaneous ° Alarm modes ° Blanking ° Cycling 28 CHAPTER 6. USAGE WITHIN THE WINDOWS 29 ° Display Colors ° Mouse ° HotKeys ° Graphics dump ° Funktion keys ° Formatter ° Lock windows ° Bill ° Preferences Within the main window you can control the commodity settings. Now to the gadgets which do not lead to sub-windows: Load Prefs Having selected this gadget, a filerequester will open up asking for a file to load new settings from, which should be used by KCommodity from now on. Using this feature you may store several settings to your (Hard)Disk. Have a look at section Save Prefs to see which data is written to that file. Save Prefs As mentioned under Load Prefs a filerequester will open up. You can now specify a file the current settings should be written to. The following data is written to that file: ° All settings of all windows ° The position / size of all windows ° Position and size of the filerequester Enable Clicking onto this gadget will invert the status after Disable. All of the program`s functions will be reenabled. CHAPTER 6. USAGE WITHIN THE WINDOWS 30 Disable Selecting this gadget will turn off almost all of the program`s functions. Touched are the following features: ° The window activator ° The mouse accelerator ° The keystroke clicker ° The screen / window cycling ° LeftyMouse ° ESC Window Close ° Mapping of Umlauts ° Screen / mouse blanker ° The function keys ° All HotKeys Please remember that KCommodity`s windows can not be opened via HotKey anymore. You will have to use either the AppIcon, AppMenuItem or use the Exchange program to open the program`s main window and from there you can open the other windows. Of course you can reenable KCommodity using the Exchange program. Hide Closes KCommodity`s main window. Quit This gadget was integrated only for test purposes. It will quit KCommodity, but anyway who really wants to quit the program :-) CHAPTER 6. USAGE WITHIN THE WINDOWS 31 6.1.1 Functions, which can not be reached via gadgets There are two functions within the main window, which can not be reached via gadgets. Therefore you will have to use the menue. Save Preferences This menu entry within the Project menu saves the current settings under the same name as specified under Save Preferences as, or it will use the default name. About This entry will open up a small window giving infor- mation about KCommodity`s version. Furthermore you can print out the registration form, which you might have done already, here. 6.2 The Settings window Within this window you can turn several functions on and off. These func- tions do not require more specific input, just on and off. Now to the gadgets` descriptions: Display clock/mem This gadget de- / activates the time / memory display. The display will either be shown within the Workbench titlebar or in a separate window. Where the display should reside can be selected using Display in window. Display in window This gadget allows you to specify the place of the time / memory display. If Display in window is active the output will be redirected to a small status window which can be dragged all over the Workbench screen and may be moved behind / in front of others. The program remembers the window`s position so that it will remain on the same position the next time it will be opened. Furthermore the position will be written to the Preferences file to have the location available the next time the program is started. If the gadget is deactivated the display will appear in the rightmost corner of the Workbench titlebar. CHAPTER 6. USAGE WITHIN THE WINDOWS 32 Show time Using this gadget you may disable the time display, so that only the date and day displays are visible. Show seconds This gadget de- / activates the displaying of seconds within the time / memory display. If you have selected the status window to be the location of the display the window will change it`s width so that the new string can fit into the titlebar. Show date You have the possibility to add the actual system date to the time / memory display. The date will appear to the left of the actual system time. As described in Show secondz the status window will correct it`s width to fit the needs. American date This option is only "visible" when Show date is active. You can choose the display to be shown in either German or American notation. ° German notation DD-MM-YY ° American notation MM-DD-YY DD stands for the day, MM for the month and finally YY for the year. The selected format also effects the format of the environment variables. Date with "." If you prefer "." between the date`s digits you may select this gadget to achieve this effect. Show day Finally you can add the actual system day to the time display. The day string will be positioned to the left of the date and of course the status window will be redrawn. CHAPTER 6. USAGE WITHIN THE WINDOWS 33 Short day string If you believe the day string to be too long you can tell KCommodity not to use the full length but to display only the first three chars of the day`s name. The abbrievations take the first three chars of the full name. Of course the status window will be redrawn. German day For you German users out there. You can tell KCommodity to print the days` names in German rather than in English. All abbrieviations will be in German, too. Auto center If this gadget is selected KCommodity will check every Screen which is about to be opened whether it has the full width or not. If not KCommodity will center the Screen horizontally, so that it resides in the middle of the display. AppIcon The program`s AppIcon may be turned on / off using this gadget, so you have total control over that icon during runtime. Write environment This gadget de- / activates the creation of environment variables for the actual system date. Variables will be generated for the day, date, and time. These variables take the names DAY, DATE, and TIME. On generation of DATE KCommodity will look at the American date and Date with "." settings, so that the date within the variable is set to German or American notation. German day will also have an effect on the generation of the DAY variable. The variables will be deleted if this function is turned off. The same will be done if you quit KCommodity. WB to front If this gadget is set, the Workbench screen will be brought to front if you try to open KCommodity`s main window. CHAPTER 6. USAGE WITHIN THE WINDOWS 34 LeftyMouse Lefties can activate "their" function here. While the LeftyMouse gadget is set the left and right mousebuttons will be swapped, that means that you will have to use the right button to click onto objects and the left button to select a menu entry. Map "Umlauts" With an selected gadget all Umlauts ä,öand üwill be automatically mapped to their pendants (ae, oe, ue). Of course this function works case-sensitive, so that KCommodity will generate Ae, Oe, and Ue if one of the keys was hit in conjunction with SHIFT. The `ß' will be mapped, too, so that there may not be any problems anymore in writing German texts not containing German Umlauts. MMB-Shift This gadget controls the MMB-Shift feature of KCommodity. If selected you do not have to hold the SHIFT key anymore to perform a multiselection. A hit on the middle mousebutton is sufficient. Drive NoClick Using this gadget you may turn on / off the noisy drive-clicking. Show Mouse X/Y If this gadget is selected KCommodity will show the actual mouse position within time / memory display page number 0. This may lead to a higher CPU usage because KCommodity will have to report every mouse movement. 6.3 The Miscellaneou window Within this window you will find settings which require more specific inputs. Key-Click As mentioned before KCommodity can emulate a keystroke click. This gadget is used to de- / activate this feature. CHAPTER 6. USAGE WITHIN THE WINDOWS 35 Click volume Using this gadget you can alter the volume for the clicking sound of Key- Click. Values between 1 and 64 are accepted. Remember that 1 is the lowest volume and 64 is the highest. ESC Window Close This gadget de- / activates the emulation of the beloved function of good PC programs. A hit on the ESC key in conjunction with a qualifier defined by ESC Qualifier will close the window underneith the mouse. Prerequistits for this function are that the window does not show a requester and that a Close Gadget is tied to the window. ESC Qualifier To the right of this gadget you find the shortcut definition which activates the ESC Window Close function. If you want to change the shortcut, simply hit on that gadget. A window will pop up giving you the possibility to change the key-combination. Simply hit the keys you want to use in conjunction with ESCAPE. If you click on OK the definition will be in use. Please remember that you have to click underneith the Text Gadget, otherwise the left mousebutton will not be recognized. Full drag This gadget controls the Full-Drag function. The qualifier defined under Dragging qualifier will not be checked if this gadget is not selected. Dragging qualifier As with ESC Qualifier you can define the qualifier for the Full Drag function. If you hit this qualifier in conjunction with the left mousebutton you can move a window without having to click onto the window`s titlebar. User Shell You can enter a command string for the Shell command here. Just enter a command with it`s parameter here as if typed into a CLI / SHELL. Here is a small example: NewSHELL CON:0/11//200/Shell CHAPTER 6. USAGE WITHIN THE WINDOWS 36 would start a new Shell process. It`s window would be 200 pixels high and it would be positioned underneith the Workbench`s titlebar. Exploding Windows Using this gadget you can de- / activate the Exploding Windows function. From/To mouse This gadget controls the focus of the Exploding Windows animation. If selected frames will be drawn from the current mouse position instead of the screens`s center. Explode frames As mentioned you can define the number of frames to be drawn for exploding / imploding animations for an active Exploding Windows function. Frames in the means of a number of rectangles to be drawn until the complete size of the window is reached. This gives users of "slower" computers the possibility to use the Exploding Windows function because they can find values which do not slow down their machine a lot. This gadget defines the number of frames to be drawn when opening a window. The value can range from 10 to 64 frames. Implode frames As mentioned above you can select a number of frames here. This time it is the number of frames to be drawn when closing a window. Size/Move frames As with the other two Slider Gadgets you can define the number of frames to be drawn for the window`s metamorphosis to it`s new position / size. 6.4 The Alarm modes window Here you control KCommodity`s alarm function and how KCommodity should behave when it`s time to wake you up. CHAPTER 6. USAGE WITHIN THE WINDOWS 37 Alarm on A set Alarm on gadget tells KCommodity to check the actual system time. If the time is equal to the alarm time specified under Alarm time KCommodity will "wake" you up. Every hour If this gadget is selected KCommodity will "wake"you up on every full hour. Show requester Normally, a small Requester will be shown if KCommodity "wakes" you up. If you deselect this gadget, this Requester will be gone. Alarm time Using this gadget you select the actual alarm time. The input does not accept seconds however, but I think hour and minutes should suffice. Sound type Here you can select the type of sound to be played on "wake-up". When using DisplayBeep() the display will flash and a soft beep will be heard. If you do not like that type of behaviour, simply select IFF Sample. Now you can select an IFF-8SVX file to be played every alarm. Select sample This gadget is only available, if you selected IFF Sample under Sound type. If you click on this gadget a Filerequester will pop up giving the possibility to select a new sample. Underneith this gadget the name of the selected sample will be displayed. 6.5 The Blanking window Here you can change settings concerning the blanking routines. The gadgets are as follows: CHAPTER 6. USAGE WITHIN THE WINDOWS 38 Blank mouse on keystroke If this gadget is active, the mouse will be blanked on every keystroke. If not, the mouse will stay where it is. Screen time This Slider Gadget is used to select the time KCommodity should wait before blanking the Screen. The countdown will always be restarted if the mouse is moved or if a key is pressed. An input of 0 turns off the Screen Blanker/Dimmer. Mouse time As mentioned under Screen time you can enter the amount of seconds before blanking the mouse here. Again, if you enter 0 the MouseBlanker will be turned off. Blanker Type This gadget is used to determine the type of screen blanking. If Blanker is shown the blanker acts as intended. KCommodity will completely blank the screen after the Screen time has elapsed. If this gadget reads Dimmer KCommodity will dimm the screen with the given Dimm Factor. Dimm Factor This gadget is only active if Blanker Type is set to Dimmer (it is not ghosted). You can now define the factor for dimming the screen. The settings can range from 1 to 48 where 1 is the brightest and 48 the darkest. Just look for the factor which suits your needs. So just find a value which suits your needs. As the dimming is done that way, as it subtracts 1 from each color value until the factor is exceeded, minor color "changes" may occure. If you prefer to have the real colors after dimming then just enter a value which is a multiple of 3. 6.6 The Cycling window You can define the behaviour of the Screen/Window cycling here. Further- more key-combinations for this feature may be defined. CHAPTER 6. USAGE WITHIN THE WINDOWS 39 Cycling enabled This gadget controls the state of the "Window / Screen cycling". Front Clicks This Slider Gadget determines the number of clicks to occure before a win- dow/screen to front is to be executed. You can choose from 1 to 5 clicks. These clicks have to occure within the Double-Click time. Middle Clicks You can define the number of clicks for the middle mousebutton (in con- junction with the key-combination), which should execute the screen cycling function. Back Clicks As mentioned under Front Clicks, this gadget determines the number of clicks for a window/screen to back. Front Key This gadget is used to change the key-combination which is to be used for a window/screen to front action. Defining this combination is done the same way as described under ESC Qualifier. Middle Key Selecting this gadget will offer the possibility to change the qualifier for the middle mousebutton which is used to cycle through screens. Back Key As described under Front Key you may redefine the key-combination for moving screens/windows to back. 6.7 Display colors If you do not like the default colors used by the titlebar / status window display you may change these. CHAPTER 6. USAGE WITHIN THE WINDOWS 40 Text front pen This gadget determines the color to be used for normal text foreground. Text back pen Using this gadget you may select a different color for the text background within the titlebar / status window. Gauge front pen This gadget selects the color the gauge should be drawn with. Gauge back pen You may define the gauge`s background color using this gadget. 6.8 The Mouse window You can alter the behaviour of the mouse here and control more settings concerning mouse handling. Window activate An activated gadget tells you that the program`s window activation routine is locked on target, that means windows will be activated with the chosen mode. Therefore Sun mouse selects the mode of activation. Sun mouse This might confuse at first sight. A set Sun mouse gadget implies that window activation is redeemed by the mouse, that means each window you touch with the mousepointer will be activated automatically. If Sun mouse is unset the mouseposition still is relevant but a window will not be activated if you touch it with the mouse. The window will only be activated if a key is pressed. So you can move the mouse over a window and start typing. Please remember that the window activation is deactivated by Window activate and not by Sun mouse. CHAPTER 6. USAGE WITHIN THE WINDOWS 41 Mouse accelerate If this gadget is active, KCommodity will accelerate the mousepointer. Acceleration Define the acceleration factor with this slider. A low value tells KCommod- ity not to accelerate too much whilst a higher value will lead to a better acceleration. Values between 2 and 10 are possible. Threshold You can set a threshold for the acceleration here. A low value means that the mouse is accelerated even if you move the pointer over short distances at a slow speed. If you define a higher value you can move the mouse over short distances without the mouse beeing accelerated. Again you can choose a value between 2 and 10. Hold X qualifier As mentioned earlier you can lock mouse movements. To the right of this gadget you see the qualifier to be used to lock the X-movements of the mousepointer. Defining this qualifier is done the same way as described under ESC Qualifier. Hold Y qualifier Same as Hold X qualifier with one exception, that this qualifier will prevent the mouse from moving in Y-direction. 6.9 The HotKeys window You can redefine all HotKeys used by KCommodity here. If you change a HotKey and the description is not correct, KCommodity will restore the previously used HotKey. There is a list of descriptions for defining a HotKey some way down that document. There is a ListView Gadget within the window which shows all available HotKeys by name. If you click on a HotKey`s name it will be displayed within a box underneith the gadget. The HotKey`s definition will be copied to the String Gadget below the box. You can now change the HotKey`s CHAPTER 6. USAGE WITHIN THE WINDOWS 42 definition here. Wrong definitions will be ignored and the previous HotKey will be restored. Here is a list of available HotKeys and their meaning. CX PopKey When describing the ToolTypes I mentioned a HotKey for opening KCom- modity`s main window. You can change this HotKey here. Each time you hit this HotKey the main window will be opened or brought to front. If WB to front is active the Workbench will be brought to front before the window is opened / popped to front. Settings This HotKey is used to open the Settings window. Blanking If you want to open the Blanking window, this HotKey may be used. Mouse To change settings within the Mouse window, this HotKey may be used. Function keys If you want to make quick changes within the Function keys window, you can open that window using this HotKey. Bill You can change the HotKey for opening the Bill window here. If you hit this HotKey while the window is open, KCommodity will close the window again. Miscellaneous As the name might tell, this HotKey is used to open the Miscellaneous window. CHAPTER 6. USAGE WITHIN THE WINDOWS 43 Cycling The Cycling window may be opened using this HotKey. HotKeys This one is used for opening the HotKeys window. Formatter If you want to format a disk, simply hit this HotKey and KCommodity`s format control panel will pop up. See The Formatter window for more information. Bill Preferences Again you can change a HotKey for opening a window. This time it`s the HotKey for the Bill Preferences window. Alarm modes To make changes within the Alarm modes window, this HotKey may be used to pop it up. Display colors If you still do not like the colors used for the display pages, you may open the Display colors window. Page This HotKey is used to change between the different display modes of the time / memory display. If you hit the HotKey the display will switch to the next page. If the last page is already beeing displayed the first page will become the active one. Here is a list of pages you can flip through: 1.Time display proably with mouse coordinates. 2.Memory display showing free Chip / Fast memory. 3.Memory display numerically showing total free memory. CHAPTER 6. USAGE WITHIN THE WINDOWS 44 4.Time display in combination with memory display. 5.Memory display showing total free memory as a gauge. 6.Online ime. All pages will either be shown within the Workbench titlebar or within the small status window (Depending on Display in window). Open Shell As mentioned above KCommodity can open a Shell by a hit on a HotKey. You can define this HotKey here. Map "Umlauts" This HotKey was implemented to de- / activate the Map "Umlauts" function, so you do not have to get to the main window each time you want to turn this function on and off. Snap memory You can define the HotKey for the "Snap memory" function here. The first time you hit the HotKey the screen will flash. This signalizes that KCommodity made a snapshot of the currently available memory. If you hit the HotKey a second time the time / memory display will change to a different page showing how much memory was freed / got lost. A possible display could be: Snapped C: 0 F: 0 This display tells you that neither chip memory nor fast memory was occupied / freed during the time between the two calls of the "Snap memory" function. If memory got lost the values shown will be negative, otherwise they will be positive. This display will only show up if the "Snap memory" function is used. The Page HotKey can not be used to switch to that page. To get back to the normal display just hit the Page HotKey. Immediate Blank This HotKey is used for an immediate Blank/Dimm, if you do not want to wait for the timeout to occure. CHAPTER 6. USAGE WITHIN THE WINDOWS 45 Display dump Having hit this HotKey, KCommodity will look for the window underneith the mouse pointer and the active screen. These two are treated as sources for the display dump. The Graphics dump window will pop up giving access to all the dumping possibilities. Lock windows This HotKey will open up the Lock windows window. Center Screen Using this HotKey you can recenter a Screen. 6.9.1 Description for defining a HotKey To ease the definition of a HotKey here is a list of key-descriptions the system "knows". You can have a look at this list if you hit the HELP key within the HotKeys window. Here is a list for qualifiers. ALT Any Alt key. RALT Only the right Alt key. LALT Only the left Alt key. SHIFT Either Shift key. RSHIFT The right Shift key. LSHIFT Only the left Shift Key. CAPSLOCK Capslock must be pressed. LCOMMAND Left Amiga key. RCOMMAND Right Amiga key. CONTROL Control Key. NUMERICPAD Keys of the Numeric Keypad are accepted. RBUTTON Right mousebutton. MIDBUTTON Middle mousebutton. LEFTBUTTON Left mousebutton. NEWPREFS Preferences have been changed. Maybe a new font was selected. CHAPTER 6. USAGE WITHIN THE WINDOWS 46 DISKREMOVED A disk was removed from a drive. DISKINSERTED A disk was inserted into a drive. These are the qualifiers you can use in almost every combination. Now we come to the descriptions of "normal" keys. A - Z, 0 - 9, etc.pp. Normal keys, as you see them on the keyboard. F1 - F10 The ten function keys. UP, DOWN, LEFT, RIGHT The cursor keys up, down, left, and right. HELP The Help key. DEL Delete key (beside HELP). BACKSPACE Backspace key. RETURN Return key. ENTER Enter on Numeric Keyboard (only, if NUMERICPAD was specified). ESC Escape key. SPACE Space. COMMA A comma. UPSTROKE The apostroph (to the left of the 1). You can use as many qualifiers as you wish, but only one key description. This is the syntax for a HotKey definition: [QUALIFIER [QUALIFIER ...]] KEY As you can see the qualifiers can be totally left out, but in how far this is usefull depends on you. 6.10 The Display dump window This is one of the most complex windows KCommodity has to offer. You have full control over the dump and the areas which are to be printed. When the Window is opened, KCommodity will search for two sources. The first one is the window underneith the mouse pointer the other one is the active screen. These sources may be used to specify the area you want to dump. A description of the gadgets available should clear the thing: CHAPTER 6. USAGE WITHIN THE WINDOWS 47 Aspect You can select the dump`s aspect. The area will either be printed Horizontal, that means horizontally, or Vertical, say vertically, rotated by 90 degrees. Shade You can select the dump-quality, better the creation of shadows. Following possibilities are offered. ° Black & White The dump will simply be black/white. ° Grey Scale 1 Grey scales will be generated for the dump. ° Grey Scale 2 Like Grey Scale 1, but this one is preferable for high-resolution dis- plays. ° Color If your printer supports color dumps, you can tell KCommodity to dump with colors. Dithering This gadget controls the dithering features, so you can control the dump quality. These are the possibilities: ° Ordered The dump dithering will be ordered. ° Halftone Dithering will be generated using the halftone method. ° Floyd-Steinberg One of the best picture manipulation algorythms around. This option uses a bit more time to produce the dump, but it will give best results. CHAPTER 6. USAGE WITHIN THE WINDOWS 48 Scaling You have several different options for scaling the output, so that you do not waist precious space on the paper. You can choose from the following scalings: ° Full Page The whole paper will be filled. ° inch x inch The values of Size will be treated as inches. ° mm x mm KCommodity asumes the Size values to be milimeters. ° cm x cm Now Size values are treated as centimeters. ° Fraction Using this setting, you can control how much percentage of the paper should be filled. The Size values are treated as these percentages. Density This gadget controls the density of the dump. The higher the density, the blacker the dark areas of the dump. Threshold You can define the threshold for black/white areas. The higher the thresh- old, the darker the dump. Image Controls the image to be created. It can either be Positive or a Negative image. Red, Green, Blue When Color is selected within the Shade Gadget, these gadgets are available to control color correction. CHAPTER 6. USAGE WITHIN THE WINDOWS 49 Size These gadgets control the scaling sizes for the dump. Take a look at Scaling to see how these values are interpreted. These values are ignored if you select Full Page. Centered This gadget tells KCommodity to horizontally center the image. Smoothing This gadget is unavailable, when using Floyd-Steinberg. Otherwise you can tell KCommodity to smothen sharp edges of the output. FormFeed When finished dumping, KCommodity will perform a FormFeed. Keep Aspect If you manually changed the scaling, this gadget tells KCommodity to keep the picture`s original aspect/scaling. Graphic This gadget controls the area to be dumped from. If Complete is selected, the whole source will be dumped, but if you select Area then you can define an area which should be dumped. X, Y, W, H These Integer Gadgets control the area to be dumped. They are unavailable if you select Complete in the Graphic gadget. Source As mentioned earlier KCommodity searches for two sources. Here you can define which of the two should be used as source for the dump. KCommodity tries to show the source`s name to the right of this gadget. CHAPTER 6. USAGE WITHIN THE WINDOWS 50 Reselect Source Clicking on this gadget will change the window`s titlebar, telling you to select a new source and hit the HotKey again. So just move the mouse over a new window/screen you wish to dump and hit the HotKey for opening the Display dump window. KCommodity will fetch data for the new sources and rearrange it`s display. Trying to dump the Dump-Window will not work, since it will be closed before the dump (that`s not the only reason :-)) and KCommodity will respond with a Requester : "Sorry, but I can`t dump myself. Please select new source.". Define Area Having selected Area you may now define the dump-area by using the mouse. The selected source will pop to front and a rectangle will be drawn from the upper left corner to the current mouse position. To set a new start position for the rectangle just click the left mousebutton. To quit simply hit the right mousebutton. The new values will be copied to KCommodity`s Integer Gadgets. Dump This gadget will start the dump. KCommodity will first check your inputs before starting the dump. If any errors are encountered KCommodity will pop up a Requester "Please check your inputs". Otherwise your printer will soon start to dump. To cancel the dump, simply hit the HotKey for opening the Display dump window. If the selected printer does not support graphics dumps KCommodity will inform you. Cancel Guess what ? It aborts the dump. 6.11 The Funktion Keys window The ten Funktion keys may be mapped with four strings. These strings can be inserted wherever character inputs are appropriate. These may be String/Integer Gadgets, Shell windows, say everthing you can type in. There are three special strings which will execute special functions. I will give you these strings here (so that nobody asks me some day): CHAPTER 6. USAGE WITHIN THE WINDOWS 51 ° MINWIN The window underneith the mouse pointer will be changed to minimal size and moved to the upper left corner of the screen. ° MAXWIN The window underneith the mouse pointer will be brought to maxi- mum size and moved to the upper left corner of the screen. ° ZIPWIN Windows equiped with a Zoom Gadget can be handeled using this command. The window underneith the mouse pointer will zip to it`s alternative size/position. F1 - F10 Just enter the strings you want KCommodity to "type" for you. Special characters and commands are supported. These are : ° ANSI - Any ANSI sequences may be entered. ° Special codes starting with n 1. \n - Return 2. \r - Return 3. \t - TAB 4. \n - \-Code ° Keydefinition between <> An example: abc<alt f1>\nHello. This would insert the definition of ALT + F1 between abc and \n. As you can see these definitions are the same as presented in Descrip- tion for defining a HotKey. Qualifier This gadget selects a new function key bank. Say it selects a new qualifier to be pressed to insert a specific string. These are the qualifiers available: ° NONE No key. ° SHIFT Either SHIFT key. CHAPTER 6. USAGE WITHIN THE WINDOWS 52 ° ALT Either ALT key. ° CONTROL CONTROL key. Active You can tell KCommodity not to watch the function keys anymore by dis- abling this gadget, so that the function keys are transparent to other applications. Ok Clicking onto this gadget will copy your settings to the internal buffer, so the new strings are available only after you clicked Ok. Cancel Aborts the definition of function keys. All changes since the pop up of the window will be lost. 6.12 The Formatter window As mentioned above KCommodity may check any inserted Disks, whether they are formated, or not. If you insert an unformated disk KCommodity will ask you whether to format the disk or not. If so, this window will pop up. Of course you can open that window manually, so that you may format a disk "by hand". The window was designed to cover all switches for the Workbench Formatter and the Formatter made by Olaf "Olsen" Barthel. To see which switches are known to the two Formatters take a look at the descriptions. Please remember that KCommodity assumes that the Formatter resides in SYS:SYSTEM/. So make sure that you keep the Formatter within this directory. Drive You may select a new drive to format a disk in. If the window was opened automatically the correct drive will already be selected. When launched, KCommodity will check for existing drives, so you can control all connected floppies. CHAPTER 6. USAGE WITHIN THE WINDOWS 53 Label Specifies the label for the Disk. Trashcan You can tell KCommodity not to create the Trashcan on the newly formatted disk. If this gadget is deselected, the disk will stay clean. This flag is supported by both of the Formatters. Quick If the disk inserted has already been formatted, but you want to get rid of files on that disk, you may select this gadget so that the disk ist wiped quickly. Only important blocks will be formatted then. Both Formatters support this flag. FFS If you want to take advantage of the new "FastFileSystem" then click on this gadget. Otherwise the disk will be formatted using the "OldFileSystem". Supported by both of the Formatters. No Verify If it takes too long to format a disk using Verify, then select this gadget to disable this feature. This flag is only supported by 'Olsen`s' Formatter. Install BootDisks have to be installed in order to boot from these disks. This flag tells the 'Olsen'-Formatter to install the disk after the format. Eject Some modern disk drives support the Eject-Command. This command tells the drive to automatically eject the disk. The 'Olsen'-Formatter supports this feature and it will send the Eject-Command to the drive after the format. CHAPTER 6. USAGE WITHIN THE WINDOWS 54 Watch Disks Tells KCommodity to watch and check every disk inserted. If you do not like this feature, simple deactivate this gadget. Ok Clicking on this gadget will start the Formatter in it`s own Shell. The only misbehaviour of Olaf Barthel`s Formatter is, that it still wants to have a RETURN before starting. The Workbench Formatter immediatly gets to work. The format will run asynchronously, so that you can still work with KCommodity. Cancel Aborts the format. 6.13 The Lock windows window This window is used to pass more information to the window activator. Besides System Requesters (like AutoRequest() and EasyRequest()), you can define windows which should not be deactivated by KCommodity, no matter where the mouse is located at or which type of window activation is selected. Unfortunately the only possibility to identify a window is to check it`s name, so windows which do not have a titlebar / name can not be used in conjunction with this feature. Window list Here you find all the names of the currently selected windows. You can scroll through this list, to change an extisting entry. Window name You can enter new window names or change existing entries here. DOS Wildcards are supported as well, so constructs like the following one are supported : #?Shell#?. This entry tells KCommodity not to deactivate any window which has a substring called Shell. Have a look at your system manual to get to know the wildcards supported by the OS. CHAPTER 6. USAGE WITHIN THE WINDOWS 55 Add window Guess what ? This gadget will generate a new entry which can be edited now. Select window If you are too lazy to write down the window`s name you can use this gadget to select a window with your mouse. Simply click on the window you wish to lock and the window`s name will be copied to the String Gadget. If you try to select a window which is not equiped with a title, KCommodity will pop up the following Requester : "Sorry, this window can not be identified by it`s title. I can`t handle something like that.". The program will not accept such a window. Delete window Will remove an entry from the list of windows. 6.14 The Bill window This window gives you information about the actual / past phone call. The actual system time (Time), the online time (Online), and the costs arising / arisen from a call (Cost), will be shown. Underneith there are five gadgets you can select the time zone and tariff with. If you change the settings during a phone call KCommodity will automatically recalculate the costs so that the program always works with the correct values and stores them to the log file. Underneith these gadgets there is another display box showing the costs for one hour for the given time zone and tariff. At the bottom border of the window there is another gadget called Log call. If it is activated data about the current phone call will be written to the log file after the modem hung up. If the gadget is deselected this data will not be stored to the file. This data will be used by Display total sum to calculate the total costs for all your phone calls. This gadget might be usefull to filter out some calls, say if you have been called by another person. This window is equipped with a Zoom Gadget. Using this gadget it is possible to easily switch between two sizes for the window, so that it does not use too much space on the Workbench (or the Public Screen). The window`s position (normal sized or "zoomed") will be written to the Preferences file. CHAPTER 6. USAGE WITHIN THE WINDOWS 56 If the window is zoomed (small), the window`s title bar will show the online time, costs, timezone, and tariff, so that you always have an overview of data. 6.15 The Preferences window Within this window all settings concerning the telephone bill calculating can be altered. You can set the time for a unit of three time zones, managed by KCommodity, for normal and cheap tarrifs, here. Let`s come to the description of the gadgets. Open up the window either by using the gadget within the main window or the HotKey. Normal Time/Unit 1-3 The gadgets with these names are used to enter the times for one unit concerning the normal tariff. The numbering from 1 to 3 is for the three available time zones. Within these gadgets only numerical inputs are al- lowed. Negative inputs will lead to a restore of the previously used value. The program believes these values to be seconds, that means you will have to calculate the correct values to enter minutes. Cheap Time/Unit 1-3 These gadgets almost have the same meaning as the ones mentioned above. The only difference is that the times entered are for the cheap tariffs of the three time zones. An example for an input Normal time / unit 1: 360 Means 6 minutes for one unit. Cheap time / unit 1: 720 Means 12 minutes for one unit. The default times correspond to these valid in Germany. Costs per unit This gadget only accepts numerical inputs, too. Enter the costs for one unit. These inputs are made in cents, so that means that an input of 23 is interpreted as 23 Pfennige (cents). Negative values will lead to a restore of the previously used value, too. CHAPTER 6. USAGE WITHIN THE WINDOWS 57 Start normal / Start cheap These gadgets are used to determine the start times for normal and cheap tariffs. KCommodity will check the system time and alter the tariff accord- ingly. Start normal is used to set the start time for normal tariff and Start cheap is used for cheap tariff. PopUp Bill window Using this CheckBox Gadget you can determine whether KCommodity should open the Bill window automatically whenever it recognizes a Carrier Detect. If the Carrier is gone (hanging up the modem) KCommodity will close the window again. If the window was already present on a Carrier Detect the program will not close the window when you hang up. Clear log Selecting this gadget the program will clear the log file with all the information about the past calls. Display total sum Attention, this gadget could get dangerous :-) When you click onto this gadget a Requester will be opened asking where to put the listing to. You can choose from a file or a window. If you selected window, a window will be opened showing information about the calls you`ve made with your modem. After all entries for one day have been listed KCommodity will print out the sum for that day. At the end of the list the program will give you the total sum for all calls made. This is also done when redirecting the listing to a file. Open Bill on You can enter a list of Public Screen names here, on which KCommodity should open the Bill window on. The names are seperated by semikolons ";". Please remember that KCommodity tries to open the window on the first screen available, that means that if the first screen of the list is present the window would never be opened on the second screen. An example: TERM;PowerPacker CHAPTER 6. USAGE WITHIN THE WINDOWS 58 KCommodity would try to open the window on Term`s1 screen. If this screen is not available the program will then try to find PowerPacker`s2 screen to open the window on. Remember that the search for the names is case-sensitive, that means KCommodity can never find a screen called "Term". Save Log to When you select this gadget a file requester will open up giving you the possibility to select a new log file. Log filename If you are already shure about the log file`s name and location you can easily enter the path / filename here. KCommodity will make sure that it is possible to write the file otherwise the previously used file will be used. Saturday - Friday These gadgets mark weekdays for use of cheap tariff the whole day. A selected gadget tells KCommodity that normal tariff is not to be used on that day. 1 A very powerful terminal program by Olaf 'Olsen' Barthel 2 A very efficient packer by Nico Francois Chapter 7 The ARexx Port KCommodity is equipped with an ARexx Port. You can manipulate almost all functions and retrieve settings via the ARexx port. The name for the ARexx Port is `KComm.1'. So if you want to send commands to that port you would have to issue ADDRESS 'KComm.1' within your ARexx script to get contact with KCommodity. If you changed the name of the port using the PORTNAME ToolType you would have to insert the name you used, of course. KCommodity offers the possibility to send return values to a calling ARexx script. To retrieve return values you must issue the following line within your script: OPTION RESULTS Having issued this command you can get the value from the ARexx vari- able called RESULT. There is a command to order return values which does not have a subsitute. This is the STATUS command. Using this program you can order some of the program`s settings. There is a list of status numbers in section Status numbers. Please remember that string parameters for a KCommodity command should be enclosed by quotes, because it could come to errors while interpreting the command. 7.1 Commands for the ARexx Port Here is a list of commands for the ARexx port. 59 CHAPTER 7. THE AREXX PORT 60 ACTIVATE 1|0 Turns the Window activate function on / off. SUNMOUSE 1|0 Turns Sun Mouse on / off. SHOWCLOCK 1|0 The time / memory display will be turned on / off. CLOCKWIN 1|0 Turning on / off the time / memory display for the status window. CLOCKWINPOS 'X/Y' You can control the status window via ARexx. This command reposi- tions the window. Please make sure that the X / Y coordinates are seper- ated by a `/' and that the complete string is enclosed by quotes. SHOWDATE 1|0 The date for the time display will be turned on / off. SHOWDAY 1|0 The day can be turned on / off via ARexx, too. SHORTDAY 1|0 Choose either the short form (1) or the long form (0) for the day string. SHOWSECS 1|0 Turn on / off the display of seconds. AMIDATE 1|0 Choose the American (1) or the Ger- man (0) format for the date string. PAGENUM 0-5 Choice of a `page' which should be displayed within the Workbench ti- tlebar or the status window. The number`s meaning is as follows: 0 - Time display plus Mouse coor- dinates. 1 - Display free Chip / Fast mem- ory. 2 - Numerically display total free memory. 3 - Timedisplay in conjunction with memory display. 4 - Display total free memory as a gauge. CHAPTER 7. THE AREXX PORT 61 5 | Online time. ALARM 1|0 Turn on / off alarm function. ALARMTIME 'HH:MM' You can set the alarm time using this command. The input should be made as descibed under Alarm time. SETENV 1|0 Turn on / off environment variables. SCREENTIME Time Set a new time for the Screen Blanker. These values are treated the same way as mentioned under Screen time. This value is created using the following way: Time = (Hours*60)+Minutes. MOUSETIME Time Use this command to set a new time for the Mouse Blanker. These val- ues are treated the same way as de- scribed under Mouse time. You cal- culate the Time the same way as de- scribed under SCREENTIME. CYCLING 1|0 This command is used to turn on / off the Cycling. CLICK 1|0 Turn on / off keystroke clicker. CLICKVOL 1-64 Of course you can set the volume for the click. LOGCALLS 1|0 The saving of data as described un- der Log call can be turned on / off. CLEARLOG Issuing this command will clear the Log file. BILLWINPOS 'X/Y' Like CLOCKWINPOS you can set the position for the Bill window using the command. BILLPOPUP 1|0 Turning on / off the PopUp Bill win- dow function. ESCCLOSE 1|0 The ESC Window Close be turned on / off via ARexx, too. MAPUMLAUT 1|0 Turn on / off Map "Umlauts" via ARexx. CHAPTER 7. THE AREXX PORT 62 SCRDIMM 1|0 Turning on / off the Screen Dimmer. ACCELERATE 1|0 Used to turn on / off the mouse ac- celerator. DRIVE 0-3 Select a new drive to be the source for the Formatter. LABEL 'Name' Define a new label for disks being for- mated using KCommodity. TRASHCAN 1|0 Control the creation of the Trashcan. QUICK 1|0 Quick formatting may be turn on and off via ARexx. FFS 1|0 You can choos between OFS and FFS to be used for formatting disks. NOVERIFY 1|0 If it takes to long to format a disk using Verify you can turn off Verify for the 'Olsen' Formatter. INSTALL 1|0 Since Bootdisks have to be installed you can tell 'Olsen`s' Formatter to in- stall the disk after the format. EJECT 1|0 Eject the disk after the format. WATCHDISKS 1|0 Tell KCommodity to check any in- serted disks, or you may turn off this feature. FORMAT Start to format a disk using the sup- plied settings. AUTOCENTER 1|0 Turn on/off Auto center. MMBSHIFT 1|0 Control the state of MMB-Shift. LOADPREFS 'Filename' This command will try to load the specifies 'Filename' as a Preferences file. 'Filename'will not be stored, so if you try to save the Preferen- ces from within the main window the previously used name will be used. SAVEPREFS 'Filename' KCommodity will try to save the Preferences file 'FileName'. The `normal' filename will be treated as described under LOADPREFS. CHAPTER 7. THE AREXX PORT 63 ENABLE Does the same as mentioned under Enable. DISABLE Same as for Disable. HIDE Closes the main window. POPUP Opens the main window. STATUS x Ask for status `x'. Have a look at Statur numbers. REVISE Activate the Revision Control Sys- tem. Have a look at the correspond- ing chapter for further information. 7.2 Status numbers Here are the status numbers returned by KCommodity corresponding to the given number. Status numbers Number Type Description 1 Num Returns the priority of the program. 2 Num Priority of the broker will be returned. 3 String The HotKey for opening the main window will be returned. 4 Bool Will return TRUE (1), if the main window should be opened on startup. If not KCommodity will return FALSE (0). 5 Bool State of the Window activate function. 6 Bool Sun Mouse active. 7 Bool Time / memory display active. 8 Bool Status window opened. 9 String Position of the status window with the format `X/Y'. CHAPTER 7. THE AREXX PORT 64 Number Type Description 10 Bool Date active 11 Bool Actual day is beeing displayed. 12 Bool Seconds are displayed. 13 Bool American date is active. 14 String HotKey for switching the time / memory display. 15 Num Pagnumber currently beeing displayed. 16 Bool Alarm active. 17 String The alarm time will be returned as (HH:MM). 18 Bool Broker active (Enable / Disable). 19 Bool Environment variables active. 20 Bool The full string for the actual day is displayed. 21 Num Time for the Screen Blanker. 22 Num Time for the Mouse Blanker. 23 Bool Cycling active. 24 Bool Keystroke clicker active. 25 Num Returns the selected volume for the clicker. 26 Bool Data about a phone call will be saved. 27 String Bill window`s postion of the form `X/Y'. 28 Bool The Bill window will be opened on a Carrier Detect. 29 Bool The Workbench will be brought to front if you try to open the main window. (WB to front) 30 Bool LeftyMouse active. 31 Bool ESC Window Close active. 32 Bool Returns the ESC Window Close`s qualifier as RawKey-Codes. 33 Bool Map "Umlauts\ active. 34 Bool AppIcon active. 35 Bool Exploding Windows active. 36 Num Number of frames for the explosion of windows. 37 Num Number of frames for the implosion of windows. CHAPTER 7. THE AREXX PORT 65 Number Type Description 38 Num Number of frames for the metamorphosis of win- dows. 39 Bool Screen Dimmer active. 40 Num Factor for the Screen Dimmer. 41 Num Returns the priority of the InputHandler. 42 Bool Determines, whether the AppMenuItem is acitve. 43 Bool This flag tells you, whether the mouse accelerator is active. 44 Num Returns the acceleration factor. 45 Num Returns the threshold. 46 Num The selected drivenumber for formating will be re- turned. 47 String The disks` label will be returned. 48 Bool Trashcan to be generated ? 49 Bool User selected Quickformatting. 50 Bool Tells you whether OFS (FALSE) or FFS (TRUE) is used to format a disk. 51 Bool Format with (FALSE) or without (TRUE) Verify ? 52 Bool Disk to be installed ? 53 Bool Returns (TRUE) if the disk is to be ejected after the format. 54 Bool Tells you whether KCommodity checks inserted disks. 55 Bool Gives information about the state of Auto center. 56 Num Returns the keycode for "window-to-front". This value is a RawKey-Code. 57 Num As with (56), but the qualifier will be returned. 58 Num Returns the keycode for "window-to-back". Again, this is a RawKey-Code. 59 Num The corresponding qualifier will be returned. 60 Num This status returns the qualifier (RawKey-Code) for the middle mousebutton. CHAPTER 7. THE AREXX PORT 66 Number Type Description 61 Num Number of clicks for "window-to-front". 62 Num Number of clicks for "window-to-back". 63 Num Number of clicks for the middle mousebutton ac- tion. 64 Bool MMB-Shift active ? 65 Num Returns the starttime for normal tariff. To get the hours and minutes do the following calcula- tion: Hour = ABS(Value/6); Minutes = REMAIN- DER(Zahl/6)*10. 66 Num Returns the starttime for cheap tariff. The value is made the same way as described under (65). 67 Bool From 67 to 73, there are boolflags for the seven weekdays. A set flag will tell you that this day is only for cheap tariff. At position 67 there is saturday and at position 73 there is friday. Description of Returnvalues Returnvalue Description Bool Either 1 (TRUE) or 0 (FALSE) will be returned. A 1 means that the corresponding function is active, but the 0 means that it is deactivated. Num A numerical value will be returned. String You get a string as result. This string takes the form described in the list. As you can see there are status numbers for almost all of the program`s settings. This might be helpful for ARexx scripts to determine which actions should be taken from within these scripts. Appendix A Error codes x could not be opened. This error code tells you that a requiered library or device could not be opened. Make sure that the desiered file is located at the correct place (Libraries within LIBS: and devices within DEVS:). It is best to always use the latest resources. Broker-Port could not be created. The port for communicating with Exchange and for controlling the main functions could not be installed. It might help you to close some windows and to stop several programs, because a lack of memory could be the reason for this error. Broker could not be set up. The program`s main control structure could not be installed. Again a lack of free memory could be the reason. Broker could not be set up correctly. The program`s main interface could not be set up. The difference between this error and the one mentioned above is that the system did not understand a definition within the structure. 67 APPENDIX A. ERROR CODES 68 Sorry, memory for InputRequest could not be allocated. Memory for the InputRequest could not be allocated. Try to free memory and restart the program. Sorry, MessagePort for InputRequest could not be created. A Message Port could not be installed. Without this port the InputHandler can not be installed. Again the reason might be lack of memory. Sorry, InputHandler could not be installed. The main InputHandler could not be installed. It may either be lack of memory of a wrong structure definition. Try to free memory and restart the program. Could not set up ARexx-Port. The ARexx Port could not be installed. Lack of memory could be the reason. Audio-Port could not be set up. ... The Message Port for the audio device could not be generated. Therefore the Key-Click option is totally disabled now. You can try to restart the program, after you have stopped several programs. Sorry, out of memory. Simple : Not enough memory to execute the desired function. Try to quit some programs which are not needed. Sorry, could not generate BitMap. The BitMap structure for the time display within the Workbench titlebar could not be initialized. The reason for this error definitely is lack of memory. APPENDIX A. ERROR CODES 69 Sorry, could not generate RastPort. Same as above. The RastPort structure for the display within the Work- bench titlebar could not be initialize. Could not allocate memory for BitPlanes. The BitPlanes for the Workbench titlebar display could not be allocated. Make sure that programs running are not consuming too much Chip memory and stop them in this case. Could not set appropriate font. The font for Workbench titlebar display could not be set. This error should never occure due to the fact that the Workbench is already using this font (but one can never know). Could not allocate memory for ARexx-Buffer. Could not allocate memory for Audio-Request. Could not allocate memory for Console-Request. Again there is not enough memory. Try to free memory and restart the program. User HotKey ... could not be set up ... One of the user-defined HotKeys for the several functions could not be in- stalled. The program will take the default HotKey now. Check your HotKey definitions. Default HotKey ... could not be set up ... A default HotKey could not be installed. The attempt failed and the pro- gram quits. Try to free memory. APPENDIX A. ERROR CODES 70 Sorry, but the AppIcon could not be installed. The AppIcon could not be displayed. This can happen if there is not suffi- cient memory or the Workbench is not present. Sorry, but the AppMenuItem could not be installed. Same as above, but the AppMenuItem could not be installed this time. The Preferences-File you attempted to load... You tried to load a Preferences file which was not generated using this version of KCommodity. Could not allocate IFF-Handle for access to file. KCommodity was not able to allocate a needed structure, in order to obtain access to an IFF-File. Try to free some memory. Could not allocate User Task-Signal. A needed task signal could not be allocated. Try to start KCommodity again, or make a reset, because this error code should never occure. Shared IDCMP-Port for windows could not be allocated. Because of the number of windows KCommodity controls, there is need for a single port, all IDCMP messages go through. This Port has to be allocated by the application. If you discover this error message, a lack of memory might be the problem. Could not allocate Port for trackdisk.device The MessagePort for the trackdisk.device could not be allocated. This device serves for checking inserted disks. Try to free some memory. Appendix B Why KCommodity ? In November 1991 I finally got to know the great Operating System OS 2.0. I was astonished of the new features and possibilities the OS offers to programmers, I immediatley wanted to start programming something made for the new environment. As I did not have the appropriate developper packages, yet, my wish should wait some more. Because the update for my Assembler arrived before the one for the C-Compiler I started to program the new OS in Assembler. As I tested DMouse1 under OS 2.0 I recognized something: With an activated window activator one could not make inputs into String Gadget while the mouse was not positioned right over the window containing the gadget. This "error" occured while using the Workbench`s AutoPoint, too. So I started to write my own window activator to eliminate that problem. With growing knowledge of the new Operating System and the ambition to start a bigger project I continued and that is how KCommodity developed. I implemented some other functions to get rid of programs doing only minor jobs. So it came as it should. The first release in ADS2. So others got to know my program and supplied usefull bugfixes and made suggestions on how to improve the program. I came to a point where it only depends on the care for my program and to steadily remove bugs reported by users. That is why I am looking forward to what you are going to report and I relly hope that more suggestions are to come. I would like to thank the following persons for giving bugreports and making suggestions: 1 A program like KCommodity by Matt Dillon 2 A subnet of FIDO 71 APPENDIX B. WHY KCOMMODITY ? 72 Christoph Reichert (my FIDO-Boss), Dirk Federlein (a good friend), Mar- ing Berndt (I got to know because of KCommodity and we call each other almost every day even thought we have not met till now), Michael Bergmann (my 1st registered user), Jürgen Rüddel (my 2nd registered user), Dirk Sp- ingler (my...), Michael Wenzel (my...), Bernd ??? (EMBO; an unknown from Z-Net), Ruud van der Veen (I never heard from again :-), Hermann Dörries (I never heard from again, too), Tammy (my girl-friend), Kai Bolay (who requested the Special qualifier, but never wrote again :-)